iT邦幫忙

2021 iThome 鐵人賽

DAY 8
0
IT管理

邁向Tech Leader的成長之路系列 第 8

7. 如何寫好document

  • 分享至 

  • xImage
  •  

Yes

前言

(因為最近時間有點少XD,所以偷偷選了比較短的影片來硬塞XD)

這篇顯然就是個蠻一般的topic,所以大家都可以看XD。如果你每次document都寫很長,但是讀者卻總是抓不到重點,一直問你問題的話,那你可能可以考慮看看這篇。

演講總結

寫文件(documentation)在業界是至關重要的,講者分享了多年寫document的經驗,列出了五項寫好文章的重點:

  1. 從讀者的角度出發:

    寫document的目的並不是為了「記錄我的技術」,而是為了「讓讀者來使用」。所以你要先想,讀者到底想要獲得哪些訊息?舉例來說,如果你要寫個user guide,你就不該寫太多關於design細節的東西,因為reader可能根本就不在乎。

  2. 寫越少越好:

    寫太多細節其實會造成你必須要去頻繁的更新,相信大家都有遇到寫document沒空更新的狀況。所以說,練習點到為止,寫到你未來有餘力去更新的深度就好。

  3. 先寫大綱:

    如果你不知道文件要怎麼寫,你可以先可以先列出些你想回答讀者的問題,用條列式,然後再填入細節。這樣的好處是確保你可以達到上面說的第一與第二個原則。

  4. 使用小黃鴨工作法:

    這源自於小黃鴨除錯法(Rubber duck debugging),意思是當你找不到bug的時候就跟小黃鴨一行一行解釋,然後你自然就會找到debug的靈感了。同樣的,當你不知道怎麼用文件闡述某件事情的時候,你可以練習用小黃鴨工作法,通常這時候你講出來的內容就會是最好的文件闡述方式。講者講到其中一個原因是,我們在寫文件的時候往往會傾向寫的「正式」,但是讀者其實對於理解正式的描述並不見得擅長,相對來說,非正式的表述往往較淺顯易懂。

    Insights are often found by simply describing the problem aloud.
    — Duck, Quack Overflow

  5. 強調可讀性:

    這裡指的可讀性是說,你可以利用排版、粗體、分段、列點、顏色各種方式來增加可讀性。而不會讓讀者看起來是在讀一個文字牆。而這技巧其實不只用在寫文件上,任何溝通的文章都是。

    講者也講了一些寫作小技巧,例如句子不要超過25個字,一段話只闡述一件事等等。有興趣的人可以自己看她的blog文章:Editing

最後講者提到,寫文件只能幫助發掘問題,但不能真正解決問題。往往你在document過程中會發現一些問題。可能是寫作流程上過於繁瑣,可能是某個概念非常難以解釋,無論你發現的問題是什麼,更重要的其實是解決這些問題,而不是寫文件去記錄這些問題。

個人心得

我自己是個很喜歡寫文件的人,主要原因是因為寫文件可以幫助整理思緒,寫完之後,也會覺得非常有成就感。其實寫文件其實就跟寫code一樣,要寫完不難,但要寫好真的需要花很長時間練習與適應,就像講者說的,重點不是你想表達什麼而是讀者想知道什麼,所以理解讀者的需求其實也是寫文件很重要的一環。

下面我列出一些個人讀後心得。

Rubber duck debugging我也是第一次聽到,但覺得這真的超真實的。自己也是遇過好幾次腦中自己想code都沒問題,但一跟別人解釋就很容易自己發現不對勁,然後就找到bug了。

至於正式的表述這件事,我自己是覺得還是要看情況,有些人的document寫的太過口語導致讀者抓不到重點。就文件來說我覺得精簡還是有必要的,只是在精簡的同時,可以少用些不太常用的單字,可以讓讀者讀起來輕鬆一點。拿新聞來比喻的話我自己覺得NYtimes的用字就比起Washington Post難懂很多XD。

可讀性這裡蠻酷的,因為我自己也是很無法接受文章一堆文字的狀況,所以自己在寫文章的時候就會盡量的用格式化的方式讓他看起來更佳易懂。她的blog文章寫了不少關於寫作可讀性的點,強烈推薦有興趣的人去看看:Editing

https://ithelp.ithome.com.tw/upload/images/20210922/20141895Dtw4ZiE0SQ.png
(圖片來源:擷取自原演講投影片

我其實對於講者的職業蠻有興趣的,她的title是Technical writer,我原本也從來沒想過世界上有這樣的職業,但因為我們團隊其實有一波討論要找technical writer,幫忙寫一些內部技術溝通與分享的文件,我才想到這個真的是可以成為一個職業的。

可能很多人會問說,document不是工程師自己寫就好了嗎,這不是個好的工程師的必備技能嗎?我自己對這個問題的答案是:文件的確是工程師要自己寫,也是個工程師該訓練的技能,但不代表公司不該請專門的人來做這件事。自己想到的原因有幾個:

  1. 每個人訓練寫文件要時間,不見得有時間等每個人慢慢成長把文件寫好。
  2. 文件作為一個溝通工具,如果大家都照自己的想法去寫跟畫架構,對於讀者來說必須要理解每個人的寫作習慣也是件很困難的事情。所以如果能限縮需要同步寫法的人在一定範圍內,相對來說文件的一致性也能提昇,對讀者來說也能提高可讀性。
  3. 如果內部文件還好,但如果是外部的話可能就更需要這樣的人存在,因為要有人負責去過濾與修飾使用的文字,畢竟外部文件對公司而言也是非常重要的公關。

上一篇
6. 恐懼支配到信任領導
下一篇
8. 你的薪水是怎麼決定的?
系列文
邁向Tech Leader的成長之路30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言